home *** CD-ROM | disk | FTP | other *** search
/ Aminet 40 / Aminet 40 (2000)(Schatztruhe)[!][Dec 2000].iso / Aminet / util / boot / BlizKick.lha / BlizKick / bkapi.lha / bkapi / bkapi.doc < prev    next >
Text File  |  2000-03-06  |  13KB  |  490 lines
  1. TABLE OF CONTENTS
  2.  
  3. bkapi.o/--background--
  4. bkapi.o/er_alloc
  5. bkapi.o/er_allocmem
  6. bkapi.o/er_allocvec
  7. bkapi.o/er_availmem
  8. bkapi.o/er_findresident
  9. bkapi.o/er_free
  10. bkapi.o/er_freevec
  11. bkapi.o/er_getarea
  12. bkapi.o/er_init
  13. bkapi.o/er_lock
  14. bkapi.o/er_nextresident
  15. bkapi.o/er_unlock
  16. bkapi.o/--background--                                 bkapi.o/--background--
  17.  
  18.    PURPOSE
  19.     If you don't know what BlizKick is get util/boot/BlizKick.lha
  20.     from aminet and read the documentation of it.
  21.  
  22.     The BlizKick EXTRES buffer is a finite space where BlizKick stores
  23.     resident tags. This area is magically added to Kickstart ROM's
  24.     internal list of memory areas to scan for resident tags. As a
  25.     result BlizKick does not need to use unreliable exec.library
  26.     KickMem & KickPtr vectors.
  27.  
  28.     This package provides easy (as easy as it can get) access to this
  29.     BlizKick EXTRES buffer.
  30.  
  31.     First application to think of, would be ROM Update software that
  32.     could easily kick in new resident module by just calling
  33.     er_allocmem and copying resident tag to memory area returned. On
  34.     next reboot this new resident tag would be activated.
  35.  
  36.     To get things even easier, one can use InternalLoadSeg with
  37.     er_allocmem as allocfunc, er_free as freefunc and dos Read() as
  38.     readfunc. Then just LoadSeg any library / device to make it
  39.     resident. Relocs and such get handled autogically! (however most
  40.     disk based libraries would not survive, namely residenttag ln_Pri
  41.     is wrong.)
  42.  
  43.     Don't expect this API to stay unchanged. There will be some sort
  44.     of MMU protection for EXTRES buffer some day... I think. However
  45.     programs respecting ERH_API_V1 will probably recompile out of the
  46.     box in the future too.
  47.  
  48.    HISTORY
  49.     1.0.1 - 17th Jan 2000, second release. fixed a typo.
  50.     1.0.0 - 15th Jan 2000, first release.
  51.  
  52.    LEGAL
  53.     Written by Harry "Piru" Sintonen, Jan 2000.
  54.     bkapi package is public domain.
  55.  
  56. bkapi.o/er_alloc                                             bkapi.o/er_alloc
  57.  
  58.    NAME
  59.     er_alloc -- allocate bytesize bytes from EXTRES memory pool
  60.  
  61.    SYNOPSIS
  62.     memoryblock = er_alloc(bytesize)
  63.     D0               D0
  64.  
  65.     void *er_alloc(ULONG);
  66.  
  67.    FUNCTION
  68.     Allocates memory from EXTRES buffer memory pool of BlizKick. This
  69.     memory area is specific in a way that resident tags will be scanned
  70.     from this area on system boot up.
  71.  
  72.     This means easy addition of system transparent resident tags.
  73.     System transparent means no kickmem or kicktag pointers will be
  74.     used.
  75.  
  76.    INPUTS
  77.     bytesize - the size of the desired block in bytes.  (will
  78.         automatically round this number to a multiple of the
  79.         system memory chunk size)
  80.  
  81.    RESULT
  82.     memoryblock - a pointer to the newly allocated memory block.
  83.         If there are no free memory regions large enough to satisfy
  84.         the request, zero will be returned.  The pointer must be
  85.         The memory block returned is quad word aligned.
  86.  
  87.    WARNING
  88.     The result of any memory allocation MUST be checked, and a viable
  89.     error handling path taken. ANY allocation may fail if memory has
  90.     been filled.
  91.  
  92.    NOTE
  93.     Allocation *will* fail if BlizKick is not run.
  94.  
  95.    SEE ALSO
  96.     er_allocmem, er_free, exec.library/Allocate
  97.  
  98. bkapi.o/er_allocmem                                       bkapi.o/er_allocmem
  99.  
  100.    NAME
  101.     er_allocmem -- AllocMem wrapper for er_alloc
  102.  
  103.    SYNOPSIS
  104.     memoryblock = er_allocmem(bytesize, attributes)
  105.     D0              D0        D1
  106.  
  107.     void *er_allocmem(ULONG, ULONG);
  108.  
  109.    FUNCTION
  110.     Allocates memory from EXTRES buffer memory pool of BlizKick. This
  111.     memory area is specific in a way that resident tags will be scanned
  112.     from this area on system boot up.
  113.  
  114.     This means easy addition of system transparent resident tags.
  115.     System transparent means no kickmem or kicktag pointers will be
  116.     used.
  117.  
  118.     This function is quite similar to er_alloc, the only difference
  119.     is that er_allocmem supports MEMF_CLEAR.
  120.  
  121.     If MEMF_CHIP is specified this function will fail.
  122.  
  123.    INPUTS
  124.     bytesize - the size of the desired block in bytes.  (will
  125.         automatically round this number to a multiple of the
  126.         system memory chunk size)
  127.  
  128.     attributes -
  129.         requirements
  130.  
  131.         MEMF_CHIP:    Will cause the allocation to fail. EXTRES
  132.                 buffer memory is in fastmem.
  133.  
  134.         options
  135.  
  136.         MEMF_CLEAR:    The memory will be initialized to all
  137.                 zeros.
  138.  
  139.    RESULT
  140.     memoryBlock - a pointer to the newly allocated memory block.
  141.         If there are no free memory regions large enough to satisfy
  142.         the request, zero will be returned. The pointer must be
  143.         checked for zero before the memory block may be used!
  144.         The memory block returned is quad word aligned.
  145.  
  146.    WARNING
  147.     The result of any memory allocation MUST be checked, and a viable
  148.     error handling path taken. ANY allocation may fail if memory has
  149.     been filled.
  150.  
  151.    NOTE
  152.     Allocation *will* fail if BlizKick is not run.
  153.  
  154.     MEMF_CLEAR is the only flag supported! Other flags will be
  155.     silentry ignored, except MEMF_CHIP that will cause allocation to
  156.     fail.
  157.  
  158.     This function is provided for completeness and also for use as
  159.     dos.library/InternalLoadSeg() allocfunc.
  160.  
  161.    SEE ALSO
  162.     er_alloc, er_free, exec.library/AllocMem, exec/memory.h
  163.  
  164. bkapi.o/er_allocvec                                       bkapi.o/er_allocvec
  165.  
  166.    NAME
  167.     er_allocvec -- allocate EXTRES memory and keep track of the size
  168.  
  169.    SYNOPSIS
  170.     memoryblock = er_allocvec(bytesize, attributes)
  171.     D0              D0        D1
  172.  
  173.     void *er_allocvec(ULONG, ULONG);
  174.  
  175.    FUNCTION
  176.     This function works similar to er_allocmem(), but tracks the size
  177.     of the allocation.
  178.  
  179.     See the er_allocmem() documentation for details.
  180.  
  181.    RESULT
  182.     memoryBlock - a pointer to the newly allocated memory block.
  183.         If there are no free memory regions large enough to satisfy
  184.         the request, zero will be returned. The pointer must be
  185.         checked for zero before the memory block may be used!
  186.         The memory block returned is *long* word aligned.
  187.  
  188.    WARNING
  189.     The result of any memory allocation MUST be checked, and a viable
  190.     error handling path taken. ANY allocation may fail if memory has
  191.     been filled.
  192.  
  193.    SEE ALSO
  194.     er_allocmem, er_freevec, exec.library/AllocVec
  195.  
  196. bkapi.o/er_availmem                                       bkapi.o/er_availmem
  197.  
  198.    NAME
  199.     er_availmem -- return EXTRES buffer memory available
  200.  
  201.    SYNOPSIS
  202.     size = er_availmem(requirements)
  203.     D0           D1
  204.  
  205.     ULONG er_availmem(ULONG);
  206.  
  207.    FUNCTION
  208.     This function returns the amount of free EXTRES buffer memory.
  209.  
  210.     To find out what the largest block is, specify MEMF_LARGEST in
  211.     attributes argument.
  212.  
  213.    WARNING
  214.     Due to the effect of multitasking, the value returned may not
  215.     actually be the amount of free memory available at that instant.
  216.     However if you have locked memory with er_lock() before, the
  217.     result is exact.
  218.  
  219.    INPUTS
  220.     requirements - MEMF_LARGEST results calculation of the size of
  221.         the largest block.
  222.  
  223.    RESULT
  224.     size - total free space remaining (or the largest free block).
  225.  
  226.    NOTE
  227.     er_availmem(MEMF_LARGEST) does a consistency check on the
  228.     memory list. In case of an error 0xFFFFFFFF is returned, and
  229.     further allocations are impossible. If memory header itself is
  230.     bad will alert with BKA_MemoryInsane.
  231.  
  232.    SEE ALSO
  233.     exec.library/AvailMem, exec/memory.h
  234.  
  235. bkapi.o/er_findresident                               bkapi.o/er_findresident
  236.  
  237.    NAME
  238.     er_findresident -- find resident tag from EXTRES buffer by name
  239.  
  240.    SYNOPSIS
  241.     resident = er_findresident(name)
  242.     D0               A1
  243.  
  244.     struct Resident *er_findresident(STRPTR);
  245.  
  246.    FUNCTION
  247.     Scan EXTRES buffer memory for Resident tag with given name.
  248.  
  249.    WARNING
  250.     You must have er_lock() on memory before calling this routine
  251.     if you intend to access the resident tag found! Keep the lock
  252.     until you're done accessing the Resident tag.
  253.  
  254.    INPUTS
  255.     name - pointer to name string
  256.  
  257.    RESULT
  258.     resident - pointer to the resident tag structure or
  259.         zero if none found.
  260.  
  261.    EXAMPLE
  262.  
  263.     struct Resident *res = NULL;
  264.  
  265.     er_lock();
  266.     if (res = er_findresident("EXTRES Handler")) {
  267.       /* do something with the resident */
  268.  
  269.       /* keep the lock until done! */
  270.     }
  271.     er_unlock();
  272.  
  273.    NOTE
  274.     exec.library/FindResident() will only find the currently *active*
  275.     resident tags in EXTRES buffer memory. Also if resident tag with
  276.     same name is found from both the ROM and EXTRES memory, the one
  277.     having newer rt_Version will be activated on boot, and thus
  278.     exec.library/FindResident() will find that particular resident.
  279.  
  280.    SEE ALSO
  281.     er_nextresident, exec.library/FindResident, exec/resident.h
  282.  
  283. bkapi.o/er_free                                               bkapi.o/er_free
  284.  
  285.    NAME
  286.     er_free -- deallocate memory from EXTRES memory pool
  287.  
  288.    SYNOPSIS
  289.     er_free(memoryblock, bytesize)
  290.         A1         D0
  291.  
  292.     void er_free(void *, ULONG);
  293.  
  294.    FUNCTION
  295.     Erase and free a region of memory, returning it to the EXTRES
  296.     memory pool.
  297.  
  298.    INPUTS
  299.     memoryblock - pointer to the memory block to free
  300.     bytesize - the size of the desired block in bytes. (will
  301.         automatically round this number to a multiple of the
  302.         system memory chunk size)
  303.  
  304.    NOTE
  305.     If a block of memory is freed twice, the system will Guru. The
  306.     Alert is AN_FreeTwice ($01000009). If you pass the wrong pointer,
  307.     you will probably see AN_MemCorrupt $01000005.
  308.  
  309.     Will also fill the memory area to be released with all ones
  310.     before releasing. This ensures no partial resident tag will
  311.     remain in unallocated memory.
  312.  
  313.     Both memory allocated by er_alloc and er_allocmem must be released
  314.     with this function!
  315.  
  316.    SEE ALSO
  317.     er_alloc, er_allocmem, exec.library/Allocate
  318.  
  319. bkapi.o/er_freevec                                         bkapi.o/er_freevec
  320.  
  321.    NAME
  322.     er_freevec -- free er_allocvec() EXTRES memory
  323.  
  324.    SYNOPSIS
  325.     er_freevec(memoryblock)
  326.            A1
  327.  
  328.     void er_freevec(void *);
  329.  
  330.    FUNCTION
  331.     Free an allocation made by the er_allocvec() call.
  332.  
  333.    NOTE
  334.     If a block of memory is freed twice, the system will Guru. The
  335.     Alert is AN_FreeTwice ($01000009). If you pass the wrong pointer,
  336.     you will probably see AN_MemCorrupt $01000005.
  337.  
  338.    INPUTS
  339.     memoryblock - pointer to the memory block to free, or NULL.
  340.  
  341.    SEE ALSO
  342.     er_allocvec, exec.library/FreeVec
  343.  
  344. bkapi.o/er_getarea                                         bkapi.o/er_getarea
  345.  
  346.    NAME
  347.     er_getarea -- get EXTRES resident module area
  348.  
  349.    SYNOPSIS
  350.     start = er_getarea(len_ptr)
  351.     D0           A0
  352.  
  353.     void *er_getarea(ULONG *);
  354.  
  355.    FUNCTION
  356.     Return lower and upper bound of memory area covered by EXTRES
  357.     buffer.
  358.  
  359.    INPUTS
  360.     len_ptr - pointer to ULONG to put area lenght to.
  361.  
  362.    RESULT
  363.     start - pointer to start of resident module area. If there's no
  364.         BlizKick EXTRES buffer available will be zero.
  365.  
  366.    NOTE
  367.     You *must* er_lock() before you read/write EXTRES buffer memory
  368.     area. Call er_unlock() when done tempering with it.
  369.  
  370.     Will return zero if BlizKick is not run.
  371.  
  372.    SEE ALSO
  373.     er_lock, er_unlock
  374.  
  375. bkapi.o/er_init                                               bkapi.o/er_init
  376.  
  377.    NAME
  378.     er_init -- initialize EXTRES buffer use
  379.  
  380.    SYNOPSIS
  381.     version = er_init()
  382.     D0
  383.  
  384.     ULONG er_init();
  385.  
  386.    FUNCTION
  387.     Initializes use of EXTRES buffer memory pool of BlizKick. This
  388.     routine must be called before using any of the other functions.
  389.  
  390.    RESULT
  391.     version - version number of EXTRES buf API available or zero
  392.         if EXTRES buf could not be found (ie. BlizKick not run).
  393.         Currently ERH_API_V1.
  394.  
  395.    SEE ALSO
  396.  
  397. bkapi.o/er_lock                                               bkapi.o/er_lock
  398.  
  399.    NAME
  400.     er_lock -- lock EXTRES buffer memory
  401.  
  402.    SYNOPSIS
  403.     er_lock()
  404.  
  405.     void er_lock(void);
  406.  
  407.    FUNCTION
  408.     Locks access to EXTRES buffer memory for this task only.
  409.  
  410.    WARNING
  411.     Be *very* careful not to keep the lock if another process you
  412.     depend/wait will try to er_lock() simultanously!
  413.  
  414.    NOTE
  415.     You *must* er_lock() before you read/write EXTRES buffer memory
  416.     area. Call er_unlock() when done tempering with it.
  417.  
  418.     er_lock() and er_unlock() nest.
  419.  
  420.    SEE ALSO
  421.     er_unlock, er_getarea
  422.  
  423. bkapi.o/er_nextresident                               bkapi.o/er_nextresident
  424.  
  425.    NAME
  426.     er_nextresident -- find first/next resident tag from EXTRES buffer
  427.  
  428.    SYNOPSIS
  429.     nextresident = er_nextresident(oldresident)
  430.     D0                   A0
  431.  
  432.     struct Resident *er_nextresident(struct Resident *);
  433.  
  434.    FUNCTION
  435.     Find first or next Resident tag from EXTRES buffer memory.
  436.  
  437.    WARNING
  438.     You *must* have er_lock() on memory before calling this routine!
  439.     Keep the lock until you're done accessing the resident tag(s).
  440.  
  441.    INPUTS
  442.     oldresident - startpoint for search, will not find this
  443.         particular resident but next. Pass NULL to find first
  444.         resident.
  445.  
  446.    RESULT
  447.     nextresident - pointer to resident tag structure or zero if no
  448.         more resident tags could be found.
  449.  
  450.    EXAMPLE
  451.  
  452.     struct Resident *res = NULL;
  453.  
  454.     er_lock();
  455.     while ( (res = er_nextresident(res)) ) {
  456.       /* do something with this Resident tag */
  457.     }
  458.     er_unlock();
  459.  
  460.    SEE ALSO
  461.     er_findresident
  462.  
  463. bkapi.o/er_unlock                                           bkapi.o/er_unlock
  464.  
  465.    NAME
  466.     er_unlock -- unlock EXTRES buffer memory
  467.  
  468.    SYNOPSIS
  469.     er_unlock()
  470.  
  471.     void er_unlock(void);
  472.  
  473.    FUNCTION
  474.     Unlock access to EXTRES buffer memory. Other tasks may bid for
  475.     access now.
  476.  
  477.    WARNING
  478.     Be *very* careful not to keep the lock if another process you
  479.     depend/wait will try to er_lock() simultanously!
  480.  
  481.    NOTE
  482.     You *must* er_lock() before you read/write EXTRES buffer memory
  483.     area. Call er_unlock() when done tempering with it.
  484.  
  485.     er_lock() and er_unlock() nest.
  486.  
  487.    SEE ALSO
  488.     er_lock, er_getarea
  489.  
  490.